{
    "cells": [
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "# Clip Vector Data with GeoPandas\n",
                "\n",
                "\n",
                "Learn how to clip geometries to the boundary of a polygon geometry\n",
                "using GeoPandas."
            ]
        },
        {
            "attachments": {},
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "The example below shows you how to clip a set of vector geometries\n",
                "to the spatial extent / shape of another vector object. Both sets of geometries\n",
                "must be opened with GeoPandas as GeoDataFrames and be in the same Coordinate\n",
                "Reference System (CRS) for the `clip` function in GeoPandas to work.\n",
                "\n",
                "This example uses example data from ``geodatasets`` ``'geoda.chicago-health'`` and\n",
                "``'geoda.groceries'``, alongside a custom rectangle geometry made with\n",
                "shapely and then turned into a GeoDataFrame.\n",
                "\n",
                "<div class=\"alert alert-info\">\n",
                "    \n",
                "Note\n",
                "\n",
                "The object to be clipped will be clipped to the full extent of the clip\n",
                "object. If there are multiple polygons in clip object, the input data will\n",
                "be clipped to the total boundary of all polygons in clip object.\n",
                "</div>\n",
                "\n"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Import Packages\n",
                "---------------\n",
                "\n",
                "To begin, import the needed packages.\n",
                "\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "import matplotlib.pyplot as plt\n",
                "import geopandas\n",
                "from shapely.geometry import box\n",
                "import geodatasets"
            ]
        },
        {
            "attachments": {},
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Get or Create Example Data\n",
                "--------------------------\n",
                "\n",
                "Below, the example GeoPandas data is imported and opened as a GeoDataFrame.\n",
                "Additionally, a polygon is created with shapely and then converted into a\n",
                "GeoDataFrame with the same CRS as the GeoPandas Chicago dataset.\n",
                "\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "chicago = geopandas.read_file(geodatasets.get_path(\"geoda.chicago_commpop\"))\n",
                "groceries = geopandas.read_file(geodatasets.get_path(\"geoda.groceries\")).to_crs(chicago.crs)\n",
                "\n",
                "# Create a subset of the Chicago data that is just the South American continent\n",
                "near_west_side = chicago[chicago[\"community\"] == \"NEAR WEST SIDE\"]\n",
                "\n",
                "# Create a custom polygon\n",
                "polygon = box(-87.8, 41.90, -87.5, 42)\n",
                "poly_gdf = geopandas.GeoDataFrame([1], geometry=[polygon], crs=chicago.crs)"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Plot the Unclipped Data\n",
                "-----------------------\n",
                "\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(12, 8))\n",
                "chicago.plot(ax=ax1)\n",
                "poly_gdf.boundary.plot(ax=ax1, color=\"red\")\n",
                "near_west_side.boundary.plot(ax=ax2, color=\"green\")\n",
                "groceries.plot(ax=ax2, color=\"purple\")\n",
                "ax1.set_title(\"All Unclipped Chicago Communities\", fontsize=20)\n",
                "ax2.set_title(\"All Unclipped Groceries\", fontsize=20)\n",
                "ax1.set_axis_off()\n",
                "ax2.set_axis_off()\n",
                "plt.show()"
            ]
        },
        {
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Clip the Data\n",
                "--------------\n",
                "\n",
                "The object on which you call `clip` is the object that will\n",
                "be clipped. The object you pass is the clip extent. The returned output\n",
                "will be a new clipped GeoDataFrame. All of the attributes for each returned\n",
                "geometry will be retained when you clip.\n",
                "\n",
                "<div class=\"alert alert-info\">\n",
                "\n",
                "Note\n",
                "\n",
                "Recall that the data must be in the same CRS in order to use the\n",
                "`clip` method. If the data are not in the same CRS, be sure to use\n",
                "the GeoPandas `GeoDataFrame.to_crs` method to ensure both datasets\n",
                "are in the same CRS.\n",
                "</div>\n",
                "\n"
            ]
        },
        {
            "attachments": {},
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "Clip the Chicago Data\n",
                "--------------------\n",
                "\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {
                "tags": [
                    "nbsphinx-thumbnail"
                ]
            },
            "outputs": [],
            "source": [
                "chicago_clipped = chicago.clip(polygon)\n",
                "\n",
                "# Plot the clipped data\n",
                "# The plot below shows the results of the clip function applied to the chicago\n",
                "# sphinx_gallery_thumbnail_number = 2\n",
                "fig, ax = plt.subplots(figsize=(12, 8))\n",
                "chicago_clipped.plot(ax=ax, color=\"purple\")\n",
                "chicago.boundary.plot(ax=ax)\n",
                "poly_gdf.boundary.plot(ax=ax, color=\"red\")\n",
                "ax.set_title(\"Chicago Clipped\", fontsize=20)\n",
                "ax.set_axis_off()\n",
                "plt.show()"
            ]
        },
        {
            "attachments": {},
            "cell_type": "markdown",
            "metadata": {},
            "source": [
                "<div class=\"alert alert-info\">\n",
                "    \n",
                "Note\n",
                "\n",
                "For historical reasons, the clip method is also available as a top-level function `geopandas.clip`.\n",
                "It is recommended to use the method as the function may be deprecated in the future.\n",
                "</div>\n",
                "\n",
                "Clip the groceries Data\n",
                "----------------------\n",
                "\n"
            ]
        },
        {
            "cell_type": "code",
            "execution_count": null,
            "metadata": {},
            "outputs": [],
            "source": [
                "groceries_clipped = groceries.clip(near_west_side)\n",
                "\n",
                "# Plot the clipped data\n",
                "# The plot below shows the results of the clip function applied to the capital cities\n",
                "fig, ax = plt.subplots(figsize=(12, 8))\n",
                "groceries_clipped.plot(ax=ax, color=\"purple\")\n",
                "near_west_side.boundary.plot(ax=ax, color=\"green\")\n",
                "ax.set_title(\"Groceries Clipped\", fontsize=20)\n",
                "ax.set_axis_off()\n",
                "plt.show()"
            ]
        }
    ],
    "metadata": {
        "kernelspec": {
            "display_name": "Python 3",
            "language": "python",
            "name": "python3"
        },
        "language_info": {
            "codemirror_mode": {
                "name": "ipython",
                "version": 3
            },
            "file_extension": ".py",
            "mimetype": "text/x-python",
            "name": "python",
            "nbconvert_exporter": "python",
            "pygments_lexer": "ipython3",
            "version": "3.10.8"
        }
    },
    "nbformat": 4,
    "nbformat_minor": 4
}
